Skip to main content

8.2 - What Your Bot Can't See - API Limitations

8.2. The Fog of Ignorance: API Limitations​

The StarCraft II API is a window into the game, but it is not a perfect one. There are several key pieces of information that are intentionally hidden from your bot to create a more "human-like" challenge.

Understanding what your bot cannot see is just as important as knowing what it can. It prevents you from trying to access data that doesn't exist and forces you to develop intelligent strategies—like scouting and inference—to work around these limitations. Your bot is a perfect observer of what's visible, but it is not omniscient.

The Core Limitation: You See State, Not Intent​

The fundamental design of the API is that it tells you the current state of the game, but it hides the enemy's future plans and ongoing actions.

+-----------------------------------+   You CAN see this...
| Enemy has a Spire.                |   (The current state)
+-----------------------------------+
                 |
                 v
+-----------------------------------+   You CANNOT see this...
| Spire is researching +1 Air Attack|   (An ongoing action/intent)
+-----------------------------------+
                 |
                 v
+-----------------------------------+   You CAN see this...
| Enemy Mutalisk has +1 attack.     |   (The new state, once complete)
+-----------------------------------+

Key Categories of Missing Information​

CategorySpecific Information Your Bot CANNOT SeeWhat This Means for Your Bot's Strategy
1. Enemy Actions- Production Queues: What units are being built in an enemy Barracks or Gateway.
- Worker Assignments: Whether an enemy worker is mining minerals, gas, or building a proxy.
- Research Progress: The progress bar of an ongoing enemy upgrade.		Scouting is mandatory. You must infer the enemy's army composition and tech choices by visually inspecting their structures and units. You cannot simply query their production.
2. Unit-Specific States- Interceptor Count: The number of Interceptors on an enemy Carrier.
- Adept Shade Timers: The remaining duration of an Adept's shade.
- Lock-On Targets: The target of an enemy Cyclone's Lock-On or a Widow Mine's attack.		You must treat these units as black boxes. For example, you have to assume any Carrier is a full threat, and you must react to the effect of a Cyclone's lock-on, not the targeting itself.
3. Global Abilities & Buffs- Enemy Chronoboost: Whether an enemy Nexus is using Chronoboost or what it is targeting.
- MULEs: You can see a MULE, but you get no special notification of it being called down.		You must develop game sense. If an enemy's army appears faster than expected, you should infer that Chronoboost or MULEs may have been a factor, but you can't confirm it directly.
4. Player-Specific Information- Player Camera: Where your opponent is currently looking on the map.
- Enemy Resources: You cannot see the enemy's mineral or gas count directly.		This is the ultimate "fog of war." You must scout to estimate the enemy's economic strength and guess where their attention might be focused.

A Developer's Checklist: Working Around Limitations​

Since you cannot access this data directly, your bot must be programmed to act like a real player and infer information.

  • Scout Early, Scout Often: Is the enemy expanding? Do they have a lot of production buildings? Are they building high-tech structures? Scouting is your only way to answer these questions.
  • Analyze Army Composition: If you see a lot of Zealots, the enemy is likely not going for air units. If you see a Stargate, you must prepare for air threats.
  • Track Known Upgrades: When you see an enemy unit with a visible upgrade (e.g., a Marine with Stimpack), you can record that this upgrade is complete for the rest of the game.
  • Develop Heuristics: Create "rules of thumb" for your bot. For example: "If it is past the 5-minute mark and I have not seen the enemy expand, assume they are preparing an all-in attack."

Your bot's intelligence is not measured by its ability to access hidden data, but by its ability to form a coherent and effective strategy in the face of incomplete information.